IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat3/lmsgi.z/lmsgi

Text File | 2002-10-03 | 24.7 KB | 925 lines

llllmmmmssssggggiiii((((3333))))                                                              llllmmmmssssggggiiii((((3333))))



NNNNAAAAMMMMEEEE
     lmsgi : license_init, license_chk_out, license_chk_in, license_timer,
     license_set_attr, license_expdate, license_errstr, license_status,
     license_free - SGI FFFFLLLLEEEEXXXXllllmmmm library

HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE
     #include <lmsgi.h>

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     This manual page describes the SGI interface to _l_i_b_l_m_s_g_i._a, the SGI
     extension to Globetrotter Software's FLEXlm library.  This library
     supports the interfaces provided by FLEXlm as well as the functions
     described here.

     The SGI interface defines a small set of functions for licensing your
     software using the FLEXlm, and consists of the following calls:

          license_init
          license_chk_out
          license_chk_in
          license_timer
          license_set_attr
          license_expdate
          license_errstr
          license_status
          license_free
          get_job

     When using any of the liblmsgi library functions you must include the
     following header and macro in your source file:

             #include <lmsgi.h>

             LM_CODE(code, ENCRYPTION_CODE_1, ENCRYPTION_CODE_2,
                     VENDOR_KEY1, VENDOR_KEY2, VENDOR_KEY3,
                     VENDOR_KEY4, VENDOR_KEY5);

     The -_l_l_m_s_g_i flag must be given to the C compiler to link programs which
     contain calls to FLEXlm functions.

             cc file.o -llmsgi

EEEENNNNVVVVIIIIRRRROOOONNNNMMMMEEEENNNNTTTT
     The following environment variables will modify the behavior of
     applications licensed with this library.

     LLLLMMMM____LLLLIIIICCCCEEEENNNNSSSSEEEE____FFFFIIIILLLLEEEE
          If set, specifies the name of one or more FLEXlm license files.
          Multiple files can be specified by separating them with a colon (::::).
          The specified files are checked first for FLEXlm licenses.





                                                                        PPPPaaaaggggeeee 1111






llllmmmmssssggggiiii((((3333))))                                                              llllmmmmssssggggiiii((((3333))))



     LLLLMMMM____LLLLIIIICCCCEEEENNNNSSSSEEEE____DDDDBBBB
          If set, specifies the name of a license file database.  A license
          file database is a file which contains a list of one or more FLEXlm
          license files and/or directories containing FLEXlm license files.

          If _L_M__L_I_C_E_N_S_E__D_B is not defined the default license file database,
          /_v_a_r/_f_l_e_x_l_m/_l_i_c_e_n_s_e_f_i_l_e._d_b, is used.

          The format of a license file database is one file or directory per
          line.  Comments are indicated by a pound sign '#' in the first
          column of the line.  Blank lines are ignored.  Trailing and/or
          leading whitespace is not allowed on a line.

          Any directory listed in the file is searched for filenames matching
          "*._d_a_t".  Any subdirectory is also searched (recursively).  All file
          names must also end with the "*._d_a_t" extension.


     If no license files have been defined by either the _L_M__L_I_C_E_N_S_E__F_I_L_E or
     _L_M__L_I_C_E_N_S_E__D_B environment variables, the default FLEXlm license file is
     /_v_a_r/_f_l_e_x_l_m/_l_i_c_e_n_s_e._d_a_t.


































                                                                        PPPPaaaaggggeeee 2222






llllmmmmssssggggiiii((((3333))))                                                              llllmmmmssssggggiiii((((3333))))



NNNNAAAAMMMMEEEE
     license_init - Initializes the FFFFLLLLEEEEXXXXllllmmmm library.

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     #include <lmsgi.h>

     int license_init (VENDORCODE* code, char *vendorname,
                       boolean_t heartbeat);


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     _l_i_c_e_n_s_e__i_n_i_t() initializes the FFFFLLLLEEEEXXXXllllmmmm library and creates a license job.
     All subsequent calls to license_init() create new license jobs.  Each
     license is independent.


     ccccooooddddeeee Use the global variable "code" which was defined by the LM_CODE
          macro (see above).

     vvvveeeennnnddddoooorrrrnnnnaaaammmmeeee
          The name of the vendor daemon to use.

     hhhheeeeaaaarrrrttttbbbbeeeeaaaatttt
          This is B_FALSE or B_TRUE.  If B_FALSE, then a default heartbeat
          protocol is implemented.  FFFFLLLLEEEEXXXXllllmmmm will generate a SIGALRM at every
          LM_A_CHECK_INTERVAL.  This will make a call to license_timer().  If
          B_TRUE, then the SIGALRM is not generated, and it is up the
          application to call license_timer() periodically.


EEEEXXXXAAAAMMMMPPPPLLLLEEEE
     /*
      * The following code initializes the FFFFLLLLEEEEXXXXllllmmmm library and
      * uses sgifd as the vendor daemon. If any errors are detected,
      * then display them.
      */

     if ( license_init (&code, "sgifd", B_FALSE) < 0 ) {
             printf ("Initialization error: %s\n", license_errstr());
     }


DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
     license_init() returns a 0 upon success or a value less than 0 if an
     error is detected.  The error string can viewed via license_errstr().










                                                                        PPPPaaaaggggeeee 3333






llllmmmmssssggggiiii((((3333))))                                                              llllmmmmssssggggiiii((((3333))))



NNNNAAAAMMMMEEEE
     license_chk_out - Attempts to check out a license.

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     #include <lmsgi.h>

     int license_chk_out(VENDORCODE *code, char *feature, char *version);


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     _l_i_c_e_n_s_e__c_h_k__o_u_t() checks out one (or more) license(s) for the specified
     feature and, for counted licenses, keeps the daemon up to date on the
     status of the process using the license(s).


     ccccooooddddeeee Use the global variable "code" which was defined by the LM_CODE
          macro (see above).

     ffffeeeeaaaattttuuuurrrreeee
          The ASCII feature name desired.

     vvvveeeerrrrssssiiiioooonnnn
          The version of the feature desired in floating point format, 3
          decimal places max.  This value must be less than or equal to the
          version number in the license file for the check out to succeed.

     The default behavior of this library when a license request fails is to
     print the standard SGI feature not found message and exit.  To override
     this behavior, applications should set the attribute
     _L_M_S_G_I__N_O__S_U_C_H__F_E_A_T_U_R_E using _l_i_c_e_n_s_e__s_e_t__a_t_t_r to register their own
     callback before calling license_chk_out.


DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
     license_chk_out() returns a 0 upon success or a value less than 0 if an
     error is detected.  The error string can viewed via license_errstr().



















                                                                        PPPPaaaaggggeeee 4444






llllmmmmssssggggiiii((((3333))))                                                              llllmmmmssssggggiiii((((3333))))



NNNNAAAAMMMMEEEE
     license_chk_in - Return a checked out license.

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     #include <lmsgi.h>

     int license_chk_in(char *feature, int keep_conn);


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     _l_i_c_e_n_s_e__c_h_k__i_n() checks in the license of the specified feature that had
     been previously checked out with license_chk_out().


     ffffeeeeaaaattttuuuurrrreeee
          The feature (license) name to be checked in.

     kkkkeeeeeeeepppp____ccccoooonnnnnnnn
          A non-zero means "_K_e_e_p _c_o_n_n_e_c_t_i_o_n _t_o _s_e_r_v_e_r"; a 0 means drop TCP
          connection.  A zero should always be used as the default.  Unused
          for UDP.

          Consult the _F_L_E_X_l_m _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e for more details.


EEEEXXXXAAAAMMMMPPPPLLLLEEEE
     /*
      * The following code returns the license, _d_u_m_m_y, back to the
      * server. If any errors are detected, then display them.
      */

     if ( license_chk_in ("dummy", 0) ) {
             printf ("Check in error: %s\n", license_errstr());
     }


DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
     license_chk_in() returns a 0 upon success or a value less than 0 if an
     error is detected.  The error string can viewed via license_errstr().
















                                                                        PPPPaaaaggggeeee 5555






llllmmmmssssggggiiii((((3333))))                                                              llllmmmmssssggggiiii((((3333))))



NNNNAAAAMMMMEEEE
     license_timer - Verifies the connection to the license server.

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     #include <lmsgi.h>

     void license_timer();


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     Periodic calls to _l_i_c_e_n_s_e__t_i_m_e_r() should be throughout the user's
     application.  These calls are important because they verify that the
     license currently checked out to your application remains valid.  The
     user may want to call license_timer() before important steps in the
     program (for example, before writing a file to disk).


EEEEXXXXAAAAMMMMPPPPLLLLEEEE
     /*
      * application code
      */

     license_timer();

     /*
      * some more application code and then
      * verify connection before writing to disk
      */

     license_timer();

     /*
      * some more application code
      */





















                                                                        PPPPaaaaggggeeee 6666






llllmmmmssssggggiiii((((3333))))                                                              llllmmmmssssggggiiii((((3333))))



NNNNAAAAMMMMEEEE
     license_set_attr - Used to set different FFFFLLLLEEEEXXXXllllmmmm attributes.

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     #include <lmsgi.h>

     int license_set_attr(int key, LM_A_VAL_TYPE value);


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     _l_i_c_e_n_s_e__s_e_t__a_t_t_r() set a FFFFLLLLEEEEXXXXllllmmmm attribute.  The key describes which
     attribute to set and value describes the value for that attribute.  A
     description of the attributes can be found in the FFFFLLLLEEEEXXXXllllmmmm _P_r_o_g_r_a_m_m_e_r'_s
     _G_u_i_d_e or the header file _l_m__a_t_t_r._h.


     kkkkeeeeyyyy  The FFFFLLLLEEEEXXXXllllmmmm attribute to set.

     vvvvaaaalllluuuueeee
          Value to set the key to.  Values should be of the appropriate type
          for the particular attribute, but should be cast to LM_A_VAL_TYPE.


NNNNOOOOTTTTEEEESSSS
     Four additional attributes have been defined in lmsgi:


     LLLLMMMMSSSSGGGGIIII____NNNNOOOO____SSSSUUUUCCCCHHHH____FFFFEEEEAAAATTTTUUUURRRREEEE
          A pointer to a function which is called when the requested feature
          cannot be checked out.  This function is only called if
          _l_i_c_e_n_s_e__c_h_k__o_u_t() fails with an _L_M__N_O_F_E_A_T_U_R_E error.

     LLLLMMMMSSSSGGGGIIII____33330000____DDDDAAAAYYYY____WWWWAAAARRRRNNNNIIIINNNNGGGG
          A pointer to a function which is called when the requested feature
          will expire within 30 days.

     LLLLMMMMSSSSGGGGIIII____66660000____DDDDAAAAYYYY____WWWWAAAARRRRNNNNIIIINNNNGGGG
          A pointer to a function which is called when the requested feature
          will expire within 60 days.

     LLLLMMMMSSSSGGGGIIII____99990000____DDDDAAAAYYYY____WWWWAAAARRRRNNNNIIIINNNNGGGG
          A pointer to a function which is called when the requested feature
          will expire within 90 days.

          The _l_m_s_g_i library sets default values for attributes in order to
          provide standardized error handling and error messages for SGI
          software.  To disable a pre-set attribute, either use
          _l_i_c_e_n_s_e__s_e_t__a_t_t_r() to register a new callback that provides your
          desired behavior, or register a _N_U_L_L callback to turn off the
          default behavior.

          The pre-set attributes are as follows:



                                                                        PPPPaaaaggggeeee 7777






llllmmmmssssggggiiii((((3333))))                                                              llllmmmmssssggggiiii((((3333))))



     LLLLMMMMSSSSGGGGIIII____NNNNOOOO____SSSSUUUUCCCCHHHH____FFFFEEEEAAAATTTTUUUURRRREEEE
          This attribute is set to a function which displays information on
          how to get a license for an SGI product.  This function also calls
          _e_x_i_t(), thus the application exits when the requested feature cannot
          be checked out.

     LLLLMMMMSSSSGGGGIIII____33330000____DDDDAAAAYYYY____WWWWAAAARRRRNNNNIIIINNNNGGGG
          This attribute is set to do nothing if the license is about to
          expire within 30 days.

     LLLLMMMMSSSSGGGGIIII____66660000____DDDDAAAAYYYY____WWWWAAAARRRRNNNNIIIINNNNGGGG
          This attribute is set to do nothing if the license is about to
          expire within 60 days.

     LLLLMMMMSSSSGGGGIIII____99990000____DDDDAAAAYYYY____WWWWAAAARRRRNNNNIIIINNNNGGGG
          This attribute is set to do nothing if the license is about to
          expire within 90 days.

     LLLLMMMM____AAAA____UUUUSSSSEEEERRRR____RRRREEEECCCCOOOONNNNNNNNEEEECCCCTTTT
          This attribute is set to a function which displays a message noting
          that the connection to the license server was lost, and an attempt
          is being made to reconnect to the server.

     LLLLMMMM____AAAA____UUUUSSSSEEEERRRR____RRRREEEECCCCOOOONNNNNNNNEEEECCCCTTTT____DDDDOOOONNNNEEEE
          This attribute is set to a function which displays a message noting
          that the connection to the license server was lost, and the attempt
          to reconnect to the server was successful.

     LLLLMMMM____AAAA____UUUUSSSSEEEERRRR____EEEEXXXXIIIITTTTCCCCAAAALLLLLLLL
          This attribute is set to a function which displays a message noting
          that the connection to the license server was lost, and the attempt
          to reconnect to the server has failed.  This function also calls
          _e_x_i_t(), thus the application exits when the reconnect fails.


EEEEXXXXAAAAMMMMPPPPLLLLEEEE
     /*
      * The following code sets the LM_A_RETRY_COUNT to 5.
      * If any errors are detected, then display them.
      */

     if ( license_set_attr(LM_A_RETRY_COUNT, (LM_A_VAL_TYPE) 5) ) {
             printf("Set attribute error: %s\n", license_errstr());
     }

     /*
      * The following code displays a message when a license will expire
      * within 90 days.
      */

     int expire_soon(daysLeft)
         int daysLeft;



                                                                        PPPPaaaaggggeeee 8888






llllmmmmssssggggiiii((((3333))))                                                              llllmmmmssssggggiiii((((3333))))



     {
         (void) fprintf(stderr,
                        "Your software license will expire in %d days.\n",
                        daysLeft);

         return 0;
     }

     /*
      * The following code registers a callback for a license which
      * will expire soon.
      */

     if ( license_set_attr(LMSGI_30_DAY_WARNING, (LM_A_VAL_TYPE) expire_soon) ) {
             printf("Set attribute error: %s\n", license_errstr());
     }



DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
     license_set_attr() returns a 0 upon success or a value less than 0 if an
     error is detected.  The error string can viewed via license_errstr().

































                                                                        PPPPaaaaggggeeee 9999






llllmmmmssssggggiiii((((3333))))                                                              llllmmmmssssggggiiii((((3333))))



NNNNAAAAMMMMEEEE
     license_expdate - Returns the expiration date of the feature checked out.

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     #include <lmsgi.h>

     time_t license_expdate(char *feature);


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     _l_i_c_e_n_s_e__e_x_p_d_a_t_e() returns the expiration date of a feature (license).


     ffffeeeeaaaattttuuuurrrreeee
          The name of the feature (license).


EEEEXXXXAAAAMMMMPPPPLLLLEEEE
     /*
      * The following code returns the expiration date of the
      * feature, _d_u_m_m_y.
      * If any errors are detected, then display them.
      */
     time_t feature_expdate;

     if ( ( feature_expdate = license_expdate("dummy") ) == -1 )
             printf ("Expiration date error: %s\n", license_errstr());



DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
     license_expdate() returns the expiration date of the given feature in
     seconds since 00:00:00 UTC, January 1, 1970.  If the given feature is a
     permanent feature (no expiration date) then license_expdate() returns 0.
     If an error occurs, a value of (time_t)-1 is returned.

     Any error string can viewed via license_errstr().


















                                                                       PPPPaaaaggggeeee 11110000






llllmmmmssssggggiiii((((3333))))                                                              llllmmmmssssggggiiii((((3333))))



NNNNAAAAMMMMEEEE
     license_errstr - Returns license server or system errors.

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     #include <lmsgi.h>

     char* license_errstr();


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     _l_i_c_e_n_s_e__e_r_r_s_t_r() returns the FFFFLLLLEEEEXXXXllllmmmm error string for the most recent
     FFFFLLLLEEEEXXXXllllmmmm error along with the major and minor number.  If a UUUUNNNNIIIIXXXX error is
     involved, the UUUUNNNNIIIIXXXX error description will also be included in the
     message, along with the UUUUNNNNIIIIXXXX _e_r_r_n_o.


EEEEXXXXAAAAMMMMPPPPLLLLEEEE
     /*
      * The following code prints out the error
      *
      *   Cannot find license file (-1, 73:2), No such file or directory
      *
      * when the license file cannot be accessed.
      *
      */

     printf ("%s\n", license_errstr());




























                                                                       PPPPaaaaggggeeee 11111111






llllmmmmssssggggiiii((((3333))))                                                              llllmmmmssssggggiiii((((3333))))



NNNNAAAAMMMMEEEE
     license_status - Returns the latest status of the checked out feature.

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     #include <lmsgi.h>

     int license_status(char *feature);


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     _l_i_c_e_n_s_e__s_t_a_t_u_s() returns the status of the requested feature (license).
     A return value of 0 indicates a successful return from the most recent
     call to the FFFFLLLLEEEEXXXXllllmmmm library for that feature.  A return value value less
     than 0 indicates an error from most recent call to the FFFFLLLLEEEEXXXXllllmmmm library.


     ffffeeeeaaaattttuuuurrrreeee
          The name of the feature.


EEEEXXXXAAAAMMMMPPPPLLLLEEEE
     /*
      * The following code checks the status of the most recent FFFFLLLLEEEEXXXXllllmmmm
      * library call.  If any errors occurred, then display them.
      */

     license_chk_out (&code, "dummy", "2.000");

     if ( license_status ("dummy") < 0 ) {
             printf ("error: %s\n", license_errstr());
     }
























                                                                       PPPPaaaaggggeeee 11112222






llllmmmmssssggggiiii((((3333))))                                                              llllmmmmssssggggiiii((((3333))))



NNNNAAAAMMMMEEEE
     get_job - Returns the FLEXlm job ID.

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     #include <lmsgi.h>

     LM_HANDLE *get_job(void);


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     Returns the FLEXlm job ID so that applications can use the standard
     FLEXlm functions along with the SGI interface.

     A return value of NULL indicates that there is currently no FLEXlm job
     ID.


EEEEXXXXAAAAMMMMPPPPLLLLEEEE
     LM_HANDLE *job;
     job = get_job();



































                                                                       PPPPaaaaggggeeee 11113333






llllmmmmssssggggiiii((((3333))))                                                              llllmmmmssssggggiiii((((3333))))



RRRREEEESSSSTTTTRRRRIIIICCCCTTTTIIIIOOOONNNNSSSS
     The FlexLM licensing code uses the stdio functions (_f_o_p_e_n(), _f_g_e_t_s(),
     etc). In some circumstances, a process may have more open file
     descriptors than will fit in a FILE structure (field __f_i_l_e; see
     /usr/include/stdio.h for details).  If this happens before the licensing
     calls, acquiring the license will fail with the message:

     Cannot find license file (-1,212:2) No such file or directory

     The only solution is to reduce the number of file descriptors in use when
     licensing calls are made. In practice this is only a problem with the O32
     (5.3 compatible) ABI, which uses an _u_n_s_i_g_n_e_d _c_h_a_r to hold the file
     descriptor (fd<=255).










































                                                                       PPPPaaaaggggeeee 11114444